gh-150319: Replace all documentation which says "See PEP 585"#150325
gh-150319: Replace all documentation which says "See PEP 585"#150325sirosen wants to merge 3 commits into
Conversation
The following classes in the stdlib get simple updates: - array.array - asyncio.Future - asyncio.Task - collections.defaultdict - collections.deque - contextvars.ContextVar - contextvars.Token - ctypes.Array - os.DirEntry - re.Match - re.Pattern - string.templatelib.Interpolation - string.templatelib.Template - types.MappingProxyType - queue.SimpleQueue - weakref.ref The following classes are documented publicly as functions, and are therefore updated internally (`__class_getitem__.__doc__`) but not in the public docs: - functools.partial - itertools.chain The following builtin types have updates to `__class_getitem__.__doc__` but not to any documentation pages: - BaseExceptionGroup - coroutines (from generators) - dict - enumerate - frozendict - frozenset - generators (and async generators) - list - memoryview - set - slice - tuple Special cases: - union objects are now documented as "supporting class-level []", rather than anything to do with generics. - Templates might be generic over a single type (union, in theory) or over a TypeVarTuple. As this is not currently fully settled, it is marked with a comment and a mild hint that it is a single type is used (namely, "type" is singular rather than "types", plural)
sirosen
requested review from
1st1,
AA-Turner,
JelleZijlstra,
ZeroIntensity,
asvetlov,
iritkatriel,
kumaraditya303,
lysnikolaou,
markshannon,
methane,
rhettinger and
willingc
as code owners
Documentation build overview
14 files changed ·
|
| template.strings: ('Ah! We do have ', '.') | ||
| template.values: ( 'Camembert', ) | ||
|
|
||
| Templates are :ref:`generic <generics>` over the type of the values which |
There was a problem hiding this comment.
Template is actually not generic in typeshed at the moment. There has been some low-level discussion about whether and how they should be generic.
There was a problem hiding this comment.
Hm. Given that there's debate about how it should work, I can strike this line. But what should I put in the docstring for it? Maybe just Template supports []?
There was a problem hiding this comment.
Yes, I'd remove the line from the RST docs and put something noncommittal in the __class_getitem__ docstring.
| {"__sizeof__", gen_sizeof, METH_NOARGS, sizeof__doc__}, | ||
| {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")}, | ||
| {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, | ||
| PyDoc_STR("generators are generic over the type of their values")}, |
There was a problem hiding this comment.
They are actually generic over three type variables (yield, send, and return type).
There was a problem hiding this comment.
Oh, yes! I often see these given as None. I'll fix.
| {"__sizeof__", gen_sizeof, METH_NOARGS, sizeof__doc__}, | ||
| {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")}, | ||
| {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, | ||
| PyDoc_STR("coroutines are generic over the type of their return value")}, |
There was a problem hiding this comment.
Also three typevars: yield, send, and return. (Though in practice the first two are usually given as Any and I'm not sure they have much practical use.)
| {"__sizeof__", gen_sizeof, METH_NOARGS, sizeof__doc__}, | ||
| {"__class_getitem__", Py_GenericAlias, | ||
| METH_O|METH_CLASS, PyDoc_STR("See PEP 585")}, | ||
| METH_O|METH_CLASS, PyDoc_STR("async generators are generic over the type of their values")}, |
There was a problem hiding this comment.
Two typevars: yield and send.
| {"__reduce__", slice_reduce, METH_NOARGS, reduce_doc}, | ||
| {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"}, | ||
| {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, | ||
| "slices are generic over the type of their values"}, |
There was a problem hiding this comment.
In typeshed they are generic over three typevars, for start, end, and step.
There was a problem hiding this comment.
Oof! I've made more mistakes than I wanted in this PR. Thanks for all the good catches.
| TUPLE_COUNT_METHODDEF | ||
| {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")}, | ||
| {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, | ||
| PyDoc_STR("tuples are generic over the types of their contents, with type arguments which match the types and arity of their contents")}, |
There was a problem hiding this comment.
This could use a longer explanation, mentioning the use of tuple[T, ...] for arbitrary-length tuples and tuple[A], tuple[A, B] etc., for fixed-length tuples.
There was a problem hiding this comment.
Okay, I think I'll break it out into a PyDoc_STRVAR so that I can make it more legible in that case.
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
|
Also, any reason you didn't add any wording to the documentation for the builtin generic classes (list etc.)? |
And expand the text for tuples. Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>
|
I pushed the corrections in a co-authored commit, along with
|
2 participants
This is a documentation update touching many modules, eliminating text which says "See PEP 585".
The general phrasing used is "X is generic over Y", and this is kept consistent as much as possible.
We can use different phrasing; the goal here is to be consistent in whatever we choose.
For types visible in the stdlib, documentation is also lifted up into class-level docs.
For builtins, however, the story for documenting this is in many cases more complex.
Therefore, updates to the doc pages are omitted for now.
The following classes in the stdlib get simple updates:
The following classes are documented publicly as functions, and are therefore updated internally (
__class_getitem__.__doc__) but not in the public docs:The following builtin types have updates to
__class_getitem__.__doc__but not to any documentation pages:Special cases:
union objects are now documented as "supporting class-level []", rather than anything to do with generics.
Templates might be generic over a single type (union, in theory) or over a TypeVarTuple. As this is not currently fully settled, it is marked with a comment and a mild hint that it is a single type is used
(namely, "type" is singular rather than "types", plural)
Additional issues resolved:
memoryviewis generic in #149488